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<h2>Introduction</h2> 

<a name="about"x/a> 

<h3>About this document</h3> 

<p> 

udev is targeted at Linux kernels 2.6 and beyond to provide a userspace solution 
for a dynamic /dev directory, with persistent device naming. The previous /dev 
implementation, <i>devf s</i>, is now deprecated, and udev is seen as the successor, 
udev vs devfs is a sensitive area of conversation - you should read <a 
href ="http : //kernel . org/pub/linux/utils/kernel/hotplug/udev_vs_devf s">this 
document</a> before making comparisons. 

</p> 

<p> 

Over the years, the things that you might use udev rules for has changed, as well 
as the flexibility of rules themselves. On a modern system, udev provides 
persistent naming for some device types out-of -the-box, eliminating the need for 
custom rules for those devices. However, some users will still require the extra 
level of customisation. 

</p> 

<p> 

This document assumes that you have udev installed and running OK with default 
configurations. This is usually handled by your Linux distribution. 

</p> 



<p> 

This document does not cover every single detail of rule writing, but does aim to 
introduce all of the main concepts. The finer details can be found in the udev man 
page. 

</p> 

<p> 

This document uses various examples (many of which are entirely fictional) to 
illustrate ideas and concepts. Not all syntax is explicitly described in the 
accompanying text, be sure to look at the example rules to get a complete 
understanding . 

</p> 

<a name="history"x/a> 

<h3>History</h3> 

<ul> 

<li>April 5th 2008 V0.74: Typo fixes. </li> 

<li>December 3rd 2007 V0.73: Update for new udev versions, and some miscellaneous 
improvements . </li> 

<li>October 2nd 2006 v0. 72: Fixed a typo in one of the example rules. </li> 

<li>June 10th 2006 V0.71: Misc changes based on recent feedback - thanks!</li> 
<li>June 3rd 2006 v0.7: Complete rework, to be more suited for the modern-day 
udev.</li> 

<li>May 9th 2005 v0.6: Misc updates, including information about udevinfo, groups 
and permissions, logging, and udevtest . </li> 

<li>June 20th 2004 V0.55: Added info on multiple symlinks, and some minor 
changes/updates . </li> 

<li>April 26th 2004 V0.54: Added some Debian info. Minor corrections. Re- reverted 
information about what to call your rule file. Added info about naming network 
interfaces . </li> 

<li>April 15th 2004 V0.53: Minor corrections. Added info about 
NAME{all_partitions} . Added info about other udevinfo tricks. </li> 

<li>April 14th 2004 V0.52: Reverted to suggesting using "udev. rules" until the udev 
defaults allow for other files. Minor work.</li> 

<li>April 6th 2004 V0.51: I now write suggest users to use their own "local . rules" 
file rather than prepending "udev. rules" .</li> 

<li>April 3rd 2004 v0.5: Minor cleanups and preparations for possible inclusion in 
the udev distribution. </li> 

<li>March 20th 2004 v0.4: General improvements, clarifications, and cleanups. Added 
more information about writing rules for usb-storage . </li> 

<li>February 23rd 2004 v0.3: Rewrote some parts to emphasise how sysfs naming 
works, and how it can be matched. Updated rule-writing parts to represent udev 018s 
new SYSFS{filename} naming scheme. Improved sectioning, and clarified many points. 
Added info about KDE.</li> 

<li>February 18th 2004 v0.2: Fixed a small omission in an example. Updated section 
on identifying mass-storage devices. Updated section on nvidia. </li> 

<li>February 15th 2004 v0.1: Initial publication . </li> 

</ ul> 

<h2>The concepts</h2> 

<a name="terminology"x/a> 

<h3>Terminology : devfs, sysfs, nodes, etc.</h3> 

<p> 

A basic introduction only, might not be totally accurate. 

</p> 



<p> 

On typical Linux-based systems, the <i>/dev</i> directory is used to store file- 
like device <b>nodes</b> which refer to certain devices in the system. Each node 
points to a part of the system (a device), which might or might not exist. 

Userspace applications can use these device nodes to interface with the systems 
hardware, for example, the X server will "listen to" /dev/input/mice so that it can 
relate the user's mouse movements to moving the visual mouse pointer. 

</p> 

<p> 

The original <i>/dev</i> directories were just populated with every device that 
might possibly appear in the system, /dev directories were typically very large 
because of this. <b>devfs</b> came along to provide a more manageable approach 
(noticeably, it only populated /dev with hardware that is plugged into the system), 
as well as some other functionality, but the system proved to have problems which 
could not be easily fixed. 

</p> 

<p> 

<fc»udev</b> is the "new" way of managing <i>/dev</i> directories, designed to clear 
up some issues with previous <i>/dev</i> implementations, and provide a robust path 
forward. In order to create and name <i>/dev</i> device nodes corresponding to 
devices that are present in the system, udev relies on matching information 
provided by <i>sysfs</i> with <i>rules</i> provided by the user. This documentation 
aims to detail the process of rule-writing, one of the only udev-related tasks that 
must (optionally) be performed by the user. 

</p> 

<p> 

<b>sysfs</b> is a new filesystem to the 2.6 kernels. It is managed by the kernel, 
and exports basic information about the devices currently plugged into your system, 
udev can use this information to create device nodes corresponding to your 
hardware, sysfs is mounted at <i>/sys</i> and is browseable. You may wish to 
investigate some of the files stored there before getting to grips with udev. 
Throughout this document, I will use the terms <i>/sys</i> and <i>sysfs</i> 
interchangeably. 

</p> 

<a name="why"x/a> 

<h3>Why?</h3> 

<p> 

udev rules are flexible and very powerful. Here are some of the things you can use 
rules to achieve: 

</p> 

<ul> 

<li>Rename a device node from the default name to something else</li> 

<li>Provide an alternative/persistent name for a device node by creating a symbolic 
link to the default device node</li> 

<li>Name a device node based on the output of a program</li> 

<li>Change permissions and ownership of a device node</li> 

<li>Launch a script when a device node is created or deleted (typically when a 
device is attached or unplugged)</li> 

<li>Rename network interfaces</li> 

</ ul> 

<p> 

Writing rules is <u>not</u> a workaround for the problem where no device nodes for 



your particular device exist. Even if there are no matching rules, udev will create 
the device node with the default name supplied by the kernel. 

</p> 

<p> 

Having persistently named device nodes has several advantages. Assume you own two 
USB storage devices: a digital camera and a USB flash disk. These devices are 
typically assigned device nodes <em>/dev/sda</em> and <em>/dev/sdb</em> but the 
exact assignment depends on the order which they were originally connected. This 
may cause problems to some users, who would benefit greatly if each device could be 
named persistently every time, e.g. <em>/dev/camera</em> and 
<em>/dev/f lashdisk</em> . 

</p> 

<a name="builtin"x/a> 

<h3>Built-in persistent naming schemes</h3> 

<p> 

udev provides persistent naming for some device types out of the box. This is a 
very useful feature, and in many circumstances means that your journey ends here: 
you do not have to write any rules. 

</p> 

<p> 

udev provides out-of -the-box persistent naming for storage devices in the 
<em>/dev/disk</em> directory. To view the persistent names which have been created 
for your storage hardware, you can use the following command: 

</p> 

<blockquote><pre># Is -1R /dev/disk</prex/blockquote> 

<p> 

This works for all storage types. As an example, udev has created <em>/dev/disk/by- 
id/scsi-SATA_ST3120827AS_4MSlNDXZ-part3</em> which is a persistent -named symbolic 
link to my root partition, udev creates <em>/dev/disk/by-id/usb- 
Prolific_Technology_Inc ._USB_Mass_Storage_Device-partl</em> when I plug my USB 
flash disk in, which is also a persistent name. 

</p> 

<!-- FIXME : document CDROM persistent naming when things settle down --> 

<h2>Rule writing</h2> 

<a name="files"x/a> 

<h3>Rule files and semantics</h3> 

<p> 

When deciding how to name a device and which additional actions to perform, udev 
reads a series of rules files. These files are kept in the 

<em>/etc/udev/rules . d</em> directory, and they all must have the <em> . rules</em> 
suffix. 

</p> 

<p> 

Default udev rules are stored in <em>/etc/udev/rules . d/50-udev. rules</em> . You may 
find it interesting to look over this file - it includes a few examples, and then 
some default rules proving a devfs-style /dev layout. However, you should not write 
rules into this file directly. 

</p> 



<p> 

Files in /etc/udev/rules . d/ are parsed in <b>lexical</b> order, and in some 
circumstances, the order in which rules are parsed is important. In general, you 
want your own rules to be parsed before the defaults, so I suggest you create a 
file at <em>/etc/udev/rules.d/10-local.rules</em> and write all your rules into 
this file. 

</p> 

<p> 

In a rules file, lines starting with "#" are treated as comments. Every other non- 
blank line is a rule. Rules cannot span multiple lines. 

</p> 

<p> 

One device can be matched by more than one rule. This has it's practical 
advantages, for example, we can write two rules which match the same device, where 
each one provides its own alternate name for the device. Both alternate names will 
be created, even if the rules are in separate files. It is important to understand 
that udev will <em>not</em> stop processing when it finds a matching rule, it will 
continue searching and attempt to apply every rule that it knows about. 

</p> 

<a name="syntax"x/a> 

<h3>Rule syntax</h3> 

<p> 

Each rule is constructed from a series of key-value pairs, which are separated by 
commas. <b>match</b> keys are conditions used to identify the device which the rule 
is acting upon. When <u>all</u> match keys in a rule correspond to the device being 
handled, then the rule is applied and the actions of the <b>assignment</b> keys are 
invoked. Every rule should consist of at least one match key and at least one 
assignment key. 

</p> 

<p> 

Here is an example rule to illustrate the above: 

</p> 

<blockquote><pre>KERNEL=="hdb", NAME="my_spare_disk"</prex/blockquote> 

<p> 

The above rule includes one match key ( <em>KERNEL</em> ) and one assignment key 
(<em>NAME</em>) . The semantics of these keys and their properties will be detailed 
later. It is important to note that the match key is related to its value through 
the equality operator (==), whereas the assignment key is related to its value 
through the assignment operator (=). 

</p> 

<p> 

Be aware that udev does not support any form of line continuation. Do not insert 
any line breaks in your rules, as this will cause udev to see your one rule as 
multiple rules and will not work as expected. 

</p> 

<a name="basic"x/a> 

<h3>Basic Rules</h3> 


<p> 



udev provides several different match keys which can be used to write rules which 
match devices very precisely. Some of the most common keys are introduced below, 
others will be introduced later in this document. For a complete list, see the udev 
man page. 

</p> 

<ul> 

<li><b>KERNEL</b> - match against the kernel name for the device</li> 
<li><b>SUBSYSTEM</b> - match against the subsystem of the device</li> 
<lixb>DRIVER</b> - match against the name of the driver backing the device</li> 
</ul> 

<p> 

After you have used a series of match keys to precisely match a device, udev gives 
you fine control over what happens next, through a range of assignment keys. For a 
complete list of possible assignment keys, see the udev man page. The most basic 
assignment keys are introduced below. Others will be introduced later in this 
document . 

</p> 

<ul> 

<li><b>NAME</b> - the name that shall be used for the device node</li> 
<li><b>SYMLINK</b> - a <b>list</b> of symbolic links which act as alternative names 
for the device node</li> 

</ul> 


<p> 

As hinted above, udev only creates one true device node for one device. If you wish 
to provide alternate names for this device node, you use the symbolic link 
functionality. With the <em>SYMLINK</em> assignment, you are actually maintaining a 
<em>list</em> of symbolic links, all of which will be pointed at the real device 
node. To manipulate these links, we introduce a new operator for appending to 
lists: <b>+=</b>. You can append multiple symlinks to the list from any one rule by 
separating each one with a space. 

</p> 

<blockquote><pre>KERNEL=="hdb", NAME="my_spare_disk"</prex/blockquote> 


<p> 

The above rule says: <em>match a device which was named by the kernel as hdb, and 
instead of calling it hdb, name the device node as my_spare_disk</em> . The device 
node appears at <em>/dev/my_spare_disk</em>. 

</p> 

<blockquotexpre>KERNEL=="hdb", DRIVER=="ide-disk", 
SYMLINK+="sparedisk"</prex/blockquote> 


<p> 

The above rule says: <em>match a device which was named by the kernel as 
where the driver is ide-disk. Name the device node with the default name 
a symbolic link to it named sparedisk</em> . Note that we did not specify 
node name, so udev uses the default, in order to preserve the standard 
<em>/dev</em> layout, your own rules will typically leave the NAME alone 
some SYMLINKs and/or perform other assignments. 

</p> 


hdb AND 
and create 
a device 

but create 


<blockquotexpre>KERNEL=="hdc", SYMLINK+="cdrom cdrom0"</prex/blockquote> 


<p> 



The above rule is probably more typical of the types of rules you might be writing. 
It creates two symbolic links at <em>/dev/cdrom</em> and <em>/dev/cdrom0</em>, both 
of which point at <em>/dev/hdc</em> . Again, no NAME assignment was specified, so 
the default kernel name (hdc) is used. 

</p> 

<a name="sysfsmatch"x/a> 

<h3>Matching sysfs attributes</h3> 

<p> 

The match keys introduced so far only provide limited matching capabilities. 
Realistically we require much finer control: we want to identify devices based on 
advanced properties such as vendor codes, exact product numbers, serial numbers, 
storage capacities, number of partitions, etc. 

</p> 

<p> 

Many drivers export information like this into sysfs, and udev allows us to 
incorporate sysf s-matching into our rules, using the <em>ATTR</em> key with a 
slightly different syntax. 

</p> 

<p> 

Here is an example rule which matches a single attribute from sysfs. Further detail 
will be provided later in this document which will aid you in writing rules based 
on sysfs attributes. 

</p> 

<blockquote><pre> 

SUBSYSTEM=="block" , ATTR{size}=="234441648" , SYMLINK+="my_disk" 

</pre></blockquote> 

<a name="hierarchy"x/a> 

<h3>Device hierarchy</h3> 

<p> 

The Linux kernel actually represents devices in a tree-like structure, and this 
information is exposed through sysfs and useful when writing rules. For example, 
the device representation of my hard disk device is a child of the SCSI disk 
device, which is in turn a child of the Serial ATA controller device, which is in 
turn a child of the PCI bus device. It is likely that you will find yourself 
needing to refer to information from a parent of the device in question, for 
example the serial number of my hard disk device is not exposed at the device 
level, it is exposed by its direct parent at the SCSI disk level. 

</p> 

<p> 

The four main match keys introduced so far ( KERNEL/SUBSYSTEM/DRIVER/ATTR) only 
match against values corresponding to the device in question, and do not match 
values from parent devices, udev provides variants of the match keys that will 
search upwards through the tree: 

</p> 

<ul> 

<lixb>KERNELS</b> - match against the kernel name for the device, or the kernel 
name for any of the parent devices</li> 

<lixb>SUBSYSTEMS</b> - match against the subsystem of the device, or the subsystem 
of any of the parent devices</li> 

<li><b>DRIVERS</b> - match against the name of the driver backing the device, or 



the name of the driver backing any of the parent devices</li> 

<lixb>ATTRS</b> - match a sysfs attribute of the device, or a sysfs attribute of 
any of the parent devices</li> 

</ul> 

<p> 

With hierarchy considerations in mind, you may feel that rule writing is becoming a 
little complicated. Rest assured that there are tools that help out here, which 
will be introduced later. 

</p> 

<a name="strsubst"></a> 

<h3>String substitutions</h3> 

<p> 

When writing rules which will potentially handle multiple similar devices, udev's 
<em>printf -like string substitution operators</em> are very useful. You can simply 
include these operators in any assignments your rule makes, and udev will evaluate 
them when they are executed. 

</p> 

<p> 

The most common operators are <b>%k</b> and <b>%n</b>. %k evaluates to the kernel 
name for the device, e.g. "sda3" for a device that would (by default) appear at 
<em>/dev/sda3</em> . <b>%n</b> evaluates to the kernel number for the device (the 
partition number for storage devices), e.g. "3" for <em>/dev/sda3</em> . 

</p> 

<p> 

udev also provides several other substitution operators for more advanced 
functionality. Consult the udev man page after reading the rest of this document. 
There is also an alternative syntax for these operators - <b>$kernel</b> and 
<b>$number</b> for the examples above. For this reason, if you wish to match a 
literal % in a rule then you must write <b>%%</b>, and if you wish to match a 
literal $ then you must write <b>$$</b>. 

</p> 

<p> 

To illustrate the concept of string substitution, some example rules are shown 
below. 

</p> 

<blockquote><pre> 

KERNEL=="mice" , NAME="input/%k" 

KERNEL=="loop0" , NAME="loop/%n" , SYMLINK+="%k" 

</pre></blockquote> 

<p> 

The first rule ensures that the mice device node appears exclusively in the 
<em>/dev/input</em> directory (by default it would be at <em>/dev/mice</em>) . The 
second rule ensures that the device node named loop© is created at 
<em>/dev/loop/0</em> but also creates a symbolic link at <em>/dev/loop0</em> as 
usual . 

</p> 

<p> 

The use of the above rules is questionable, as they all could be rewritten without 
using any substitution operators. The true power of these substitutions will become 
apparent in the next section. 



</p> 

<a name="strmatch"x/a> 

<h3>String matching</h3> 

<p> 

As well as matching strings exactly, udev allows you to use shell-style pattern 
matching. There are 3 patterns supported: 

</p> 

<ul> 

<li><t»*</b> - match any character, zero or more times</li> 

<li><b>?</b> - match any character exactly once</li> 

<li><b>[]</b> - match any single character specified in the brackets, ranges are 
also permitted</li> 

</ul> 

<p> 

Here are some examples which incorporate the above patterns. Note the use of the 
string substitution operators. 

</p> 

<blockquote><pre> 

KERNEL=="f d [0-9] * " , NAME="f loppy/%n" , SYMLINK+="%k" 

KERNEL=="hiddev* " , NAME="usb/%k" 

</prex/blockquote> 

<p> 

The first rule matches all floppy disk drives, and ensures that the device nodes 
are placed in the <em>/dev/floppy</em> directory, as well as creating a symbolic 
link from the default name. The second rule ensures that hiddev devices are only 
present in the <em>/dev/usb</em> directory. 

</p> 

<h2>Finding information from sysfs</h2> 

<a name="sysfstree"x/a> 

<h3>The sysfs tree</h3> 

<p> 

The concept of using interesting information from sysfs was briefly touched upon 
above. In order to write rules based on this information, you first need to know 
the names of the attributes and their current values. 

</p> 

<p> 

sysfs is actually a very simple structure. It is logically divided into 
directories. Each directory contains a number of files (<em>attributes</em>) which 
typically contain just one value. Some symbolic links are present, which link 
devices to their parents. The hierarchical structure was touched upon above. 

</p> 

<p> 

Some directories are referred to as <em>top-level device paths</em>. These 
directories represent actual devices that have corresponding device nodes. Top- 
level device paths can be classified as sysfs directories which contain a 
<em>dev</em> file, the following command will list these for you: 

</p> 



<blockquote><pre># find /sys -name dev</pre></blockquote> 

<p> 

For example, on my system, the <em>/sys/block/sda</em> directory is the device path 
for my hard disk. It is linked to it's parent, the SCSI disk device, through the 
<em>/sys/block/sda/device</em> symbolic link. 

</p> 

<p> 

When you write rules based on sysfs information, you are simply matching attribute 
contents of some files in one part of the chain. For example, I can read the size 
of my hard disk as follows: 

</p> 

<blockquote><pre> 

# cat /sys/block/sda/size 
234441648 

</pre></blockquote> 

<p> 

In a udev rule, I could use ATTR{size}=="234441648" to identify this disk. As udev 
iterates through the entire device chain, I could alternatively opt to match 
attributes in another part of the chain (e.g. attributes in 

<em>/sys/class/block/sda/device/</em>) using <em>ATTRS</em>, however there are some 
caveats when dealing with different parts of the chain which are described later. 

</p> 

<p> 

Although this serves as a useful introduction as to the structure of sysfs and 
exactly how udev matches values, manually trawling through sysfs is both time 
consuming and unnecessary. 

</p> 

<a name="udevadm"x/a> 

<h3>udevadm info</h3> 

<p> 

Enter <em>udevadm info</em>, which is probably the most straightforward tool you 
can use to construct rules. All you need to know is the sysfs device path of the 
device in question. A trimmed example is shown below: 

</p> 

<blockquote><pre> 

# udevadm info -a -p /sys/block/sda 

<span class="green"> looking at device ' /block/sda ' : 

KERNEL=="sda" 

SUBSYSTEM==" block" 

ATTR{stat}==" 128535 2246 2788977 766188 73998 317300 3132216 

5735004 0 516516 6503316" 

ATTR{ size} =="234441648" 

ATTR{removabie}=="0" 

ATTR{range}=="16" 

ATTR{dev}=="8 : 0"</span> 

<span class="blue"> looking at parent device 
1 /devices/pci0000 : 00/0000 : 00 : 07 . 0/host0/target0 : 0 : 0/0 : 0 : 0 : 0 1 : 

KERNELS=="0 : 0:0:0" 

SUBSYSTEMS=="SCSi" 



DRIVERS=="sd" 

ATTRS{ioerr_cnt}=="0x0" 

ATTRS{iodone_cnt}==" 0x31737" 

ATTRS{iorequest_cnt}==" 0x31737" 

ATTRS{iocounterbits}=="32" 

ATTRS{timeout}=="30" 

ATTRS{state}==" running" 

ATTRS{rev}=="3 . 42" 

ATTRS{model}=="ST3120827AS 

ATTRS{vendor}=="ATA 

ATTRS{scsi_level}=="6" 

ATTRS{type}=="0" 

ATTRS{queue_type}=="none" 

ATTRS{queue_depth}=="l" 

ATTRS{device_blocked}=="0"</span> 

<span class="maroon"> looking at parent device ' /devices/pci0000 : 00/0000 : 00 : 07 . 0 1 : 
KERN ELS==" 0000 : 00 : 07 .0" 

SUBSYSTEMS=="pci" 

DRlVERS=="sata_nv" 

ATTRS{vendor}=="0xl0de" 

ATTRS{device}=="0x037f "</span> 

</pre></blockquote> 

<p> 

As you can see, udevadm info simply produces a list of attributes you can use as-is 
as match keys in your udev rules. From the above example, I could produce (e.g.) 
either of the following two rules for this device: 

</p> 

<blockquote><pre> 

<span class="green">SUBSYSTEM=="block"</span>, <span 
class="green">ATTR{size}=="234441648", </span> NAME="my_hard_disk" 

<span class="green">SUBSYSTEM=="block"</span>, <span 
class="blue">SUBSYSTEMS=="scsi"</span>, <span 
class="blue">ATTRS{model}=="ST3l20827AS", </span> 
NAME="my_hard_disk"</pre></blockquote> 

<p> 

You may have noted the use of colour in the above examples. This is to demonstrate 
that while it is legal to combine the attributes from the device in question and a 
<em>single</em> parent device, you cannot mix-and-match attributes from multiple 
parent devices - your rule will not work. For example, the following rule is 
<em>invalid</em> as it attempts to match attributes from two parent devices: 

</p> 

<blockquote><pre> 

<span class="green">SUBSYSTEM=="block"</span>, <span 
class="blue">ATTRS{model}=="ST3l20827AS"</span>, <span 

class="maroon">DRIVERS=="sata_nv"</span>, NAME="my_hard_disk"</prex/blockquote> 

<p> 

You are usually provided with a large number of attributes, and you must pick a 
number of them to construct your rule. In general, you want to choose attributes 
which identify your device in a persistent and human-recognisable way. In the 
examples above, I chose the size of my disk and its model number. I did not use 
meaningless numbers such as ATTRS{iodone_cnt}=="0x31737" . 

</p> 



<p> 

Observe the effects of hierarchy in the udevadm info output. The <span 
class="green">green</span> section corresponding to the device in question uses the 
standard match keys such as KERNEL and ATTR. The <span class="blue">blue</span> and 
<span class="maroon">maroon</span> sections corresponding to parent devices use the 
parent-traversing variants such as SUBSYSTEMS and ATTRS. This is why the complexity 
introduced by the hierarchical structure is actually quite easy to deal with, just 
be sure to use the exact values that udevadm info suggests. 

</p> 

<p> 

Another point to note is that it is common for text attributes to appear in the 
udevadm info output to be padded with spaces (e.g. see ST3120827AS above). In your 
rules, you can either specify the extra spaces, or you can cut them off as I have 
done. 

</p> 

<p> 

The only complication with using udevadm info is that you are required to know the 
top-level device path (/sys/block/sda in the example above). This is not always 
obvious. However, as you are generally writing rules for device nodes which already 
exist, you can use udevadm info to look up the device path for you: 

</p> 

<blockquote><pre># udevadm info -a -p $(udevadm info -q path -n 
/dev/sda)</pre></blockquote> 

<a name="sysfsalt"></a> 

<h3>Alternative methods</h3> 

<p> 

Although udevadm info is almost certainly the most straightforward way of listing 
the exact attributes you can build rules from, some users are happier with other 
tools. Utilities such as <a href="http://www.kroah.com/linux/usb/">usbview</a> 
display a similar set of information, most of which can be used in rules. 

</p> 

<h2>Advanced topics</h2> 

<a name="ownership"x/a> 

<h3>Controlling permissions and ownership</h3> 

<p> 

udev allows you to use additional assignments in rules to control ownership and 
permission attributes on each device. 

</p> 

<p> 

The <em>GROUP</em> assignment allows you to define which Unix group should own the 
device node. Here is an example rule which defines that the <em>video</em> group 
will own the framebuffer devices: 

</p> 

<blockquotexpre>KERNEL=="f b [0-9] * " , NAME="f b/%n" , SYMLINK+="%k" , 
GROUP="video"</pre></blockquote> 

<p> 

The <em>OWNER</em> key, perhaps less useful, allows you to define which Unix user 
should have ownership permissions on the device node. Assuming the slightly odd 



situation where you would want <em>john</em> to own your floppy devices, you could 
use : 

</p> 

<blockquote><pre>KERNEL=="fd [0-9] *", OWNER=" john"</pre></blockquote> 

<p> 

udev defaults to creating nodes with Unix permissions of 0660 (read/write to owner 
and group). If you need to, you can override these defaults on certain devices 
using rules including the <em>MODE</em> assignment. As an example, the following 
rule defines that the inotify node shall be readable and writable to everyone: 

</p> 

<blockquote><pre>KERNEL=="inotif y" , NAME="misc/%k" , SYMLINK+="%k" , 
MODE="0666"</pre></blockquote> 

<a name="external-naming"x/a> 

<h3>Using external programs to name devices</h3> 

<p> 

Under some circumstances, you may require more flexibility than standard udev rules 
can provide. In this case, you can ask udev to run a program and use the standard 
output from that program to provide device naming. 

</p> 

<p> 

To use this functionality, you simply specify the absolute path of the program to 
run (and any parameters) in the <em>PROGRAM</em> assignment, and you then use some 
variant of the <em>%c</em> substitution in the NAME/SYMLINK assignments. 

</p> 

<p> 

The following examples refer to a fictional program found at 

<em>/bin/device_namer</em>. device_namer takes one command line argument which is 
the kernel name for the device. Based upon this kernel name, device_namer does its 
magic and produces some output to the usual <em>stdout</em> pipe, split into 
several parts. Each part is just a single word, and parts are separated by a single 
space. 

</p> 

<p> 

In our first example, we assume that device_namer outputs a number of parts, each 
one to form a symbolic link (alternative name) for the device in question. 

</p> 

<blockquotexpre>KERNEL=="hda" , PROGRAM="/bin/device_namer %k" , 
SYMLINK+="%c"</prex/blockquote> 

<p> 

The next example assumes that device_namer outputs two parts, the first being the 
device name, and the second being the name for an additional symbolic link. We now 
introduce the <em>%c{N}</em> substitution, which refers to part N of the output: 

</p> 

<blockquotexpre>KERNEL=="hda", PROGRAM="/bin/device_namer %k", NAME="%c{l}", 
SYMLINK+="%c{2}"</prex/blockquote> 

<p> 

The next example assumes that device_namer outputs one part for the device name, 



followed by any number of parts which will form additional symbolic links. We now 
introduce the <em>%c{N+}</em> substitution, which evaluates to part N, N+l, 

N+2, ... until the end of the output. 

</p> 

<blockquote><pre>KERNEL=="hda", PROGRAM="/bin/device_namer %k", NAME="%c{l}", 
SYMLINK+="%c{2+}"</pre></blockquote> 

<p> 

Output parts can be used in any assignment key, not only NAME and SYMLINK. The 
example below uses a fictional program to determine the Unix group which should own 
the device: 

</p> 

<blockquotexpre>KERNEL=="hda" , PROGRAM="/bin/who_owns_device %k" , 
GROUP="%c"</pre></blockquote> 

<a name="external-run"x/a> 

<h3>Running external programs upon certain events</h3> 

<p> 

Yet another reason for writing udev rules is to run a particular program when a 
device is connected or disconnected. For example, you might want to execute a 
script to automatically download all of your photos from your digital camera when 
it is connected. 

</p> 

<p> 

Do not confuse this with the <em>PROGRAM</em> functionality described above. 
<em>PROGRAM</em> is used for running programs which produce device names (and they 
shouldn't do anything other than that). When those programs are being executed, the 
device node has not yet been created, so acting upon the device in any way is not 
possible . 

</p> 

<p> 

The functionality introduced here allows you to run a program after the device node 
is put in place. This program can act on the device, however it must not run for 
any extended period of time, because udev is effectively paused while these 
programs are running. One workaround for this limitation is to make sure your 
program immediately detaches itself. 

</p> 

<p> 

Here is an example rule which demonstrates the use of the <em>RUN</em> list 
assignment : 

</p> 

<blockquotexpre>KERNEL=="sdb", RUN+="/usr/bin/my_program"</prex/blockquote> 

<p> 

When <em>/usr/bin/my_program</em> is executed, various parts of the udev 
environment are available as environment variables, including key values such as 
<em>SUBSYSTEM</em>. You can also use the <em>ACTION</em> environment variable to 
detect whether the device is being connected or disconnected - ACTION will be 
either "add" or "remove" respectively. 

</p> 


<p> 



udev does not run these programs on any active terminal, and it does not execute 
them under the context of a shell. Be sure to ensure your program is marked 
executable, if it is a shell script ensure it starts with an appropriate <a 
href =" http : //en .Wikipedia. or g/wiki/Shebang_( Unix) ">shebang</a> (e . g . 

<code># ! /bin/sh</code>) , and do not expect any standard output to appear on your 
terminal. 

</p> 

<a name="env"x/a> 

<h3>Environment interaction</h3> 

<p> 

udev provides an <em>ENV</em> key for environment variables which can be used for 
both matching and assignment. 

</p> 

<p> 

In the assignment case, you can set environment variables which you can then match 
against later. You can also set environment variables which can be used by any 
external programs invoked using the techniques mentioned above. A fictional example 
rule which sets an environment variable is shown below. 

</p> 

<blockquotexpre>KERNEL=="fd0", SYMLlNK+="f loppy", 

ENV{some_var}=" value "</pre></blockquote> 

<p> 

In the matching case, you can ensure that rules only run depending on the value of 
an environment variable. Note that the environment that udev sees will not be the 
same user environment as you get on the console. A fictional rule involving an 
environment match is shown below. 

</p> 

<blockquotexpre>KERNEL=="fd0", ENV{an_env_var}=="yes", 
SYMLINK+="floppy"</prex/blockquote> 

<p> 

The above rule only creates the <em>/dev/floppy</em> link if $an_env_var is set to 
"yes" in udev's environment. 

</p> 

<a name="options"x/a> 

<h3>Additional options</h3> 

<p> 

Another assignment which can prove useful is the <em>OPTIONS</em> list. A few 
options are available: 

</p> 

<ul> 

<li><b>all_partitions</b> - create all possible partitions for a block device, 
rather than only those that were initially detected</li> 

<li><b>ignore_device</b> - ignore the event completely</li> 

<lixb>last_rule</b> - ensure that no later rules have any effect</li> 

</ul> 

<p> 

For example, the rule below sets the group ownership on my hard disk node, and 
ensures that no later rule can have any effect: 



</p> 

<blockquote><pre>KERNEL=="sda", GROUP="disk", 
OPTIONS+="last_rule"</pre></blockquote> 


<h2>Examples</h2> 

<a name="example-printer"x/a> 

<h3>USB Printer</h3> 

<p> 

I power on my printer, and it is assigned device node <em>/dev/lp0</em> . Not 
satisfied with such a bland name, I decide to use udevadm info to aid me in writing 
a rule which will provide an alternative name: 

</p> 

<blockquote><pre> 

# udevadm info -a -p $(udevadm info -q path -n /dev/lp0) 
looking at device 1 /class/usb/lp0 ' : 

KERNEL=="lp0" 

SUBSYSTEM=="usb" 

DRIVER==" " 

ATTR{dev}=="180 : 0" 


looking at parent device 1 /devices/pci0000 : 00/0000 : 00 : Id . 0/usbl/l-l 1 : 
SUBSYSTEMS=="usb" 

ATTRS{manuf act urer}==" EPSON" 

ATTRS{product}=="USB Printer" 

ATTRS{serial}==" L72010011070626380" 

</prex/blockquote> 

<p> 

My rule becomes: 

</p> 

<blockquotexpre>SUBSYSTEM=="usb", ATTRS{serial}=="L720l00ll070626380", 
SYMLINK+="epson_680"</prex/blockquote> 

<a name="example-camera"x/a> 

<h3>USB Camera</h3> 

<p> 

Like most, my camera identifies itself as an external hard disk connected over the 
USB bus, using the SCSI transport. To access my photos, I mount the drive and copy 
the image files onto my hard disk. 

</p> 

<p> 

Not all cameras work in this way: some of them use a non-storage protocol such as 
cameras supported by <a href="http://www.gphoto.org/">gphoto2</a>. In the gphoto 
case, you do not want to be writing rules for your device, as is it controlled 
purely through userspace (rather than a specific kernel driver). 

</p> 

<p> 

A common complication with USB camera devices is that they usually identify 
themselves as a disk with a single partition, in this case <em>/dev/sdb</em> with 
<em>/dev/sdbl</em> . The sdb node is useless to me, but sdbl is interesting - this 



is the one I want to mount. There is a problem here that because sysfs is chained, 
the useful attributes which udevadm info produces for /dev/sdbl are identical to 
the ones for /dev/sdb. This results in your rule potentially matching <u>both</u> 
the raw disk and the partition, which is not what you want, your rule should be 
<b>specif ic</b> . 

</p> 

<p> 

To get around this, you simply need to think about what differs between sdb and 
sdbl. It is surprisingly simple: the name itself differs, so we can use a simple 
pattern match on the NAME field. 

</p> 

<blockquote><pre> 

# udevadm info -a -p $(udevadm info -q path -n /dev/sdbl) 
looking at device ' /block/sdb/sdbl ' : 

KERNEL=="sdbl" 

SUBSYSTEM==" block" 

looking at parent device 1 /devices/pci0000 : 00/0000 : 00 : 02 . 1/usbl/l-l/l- 
1:1. 0/host6/target6 : 0 : 0/6 : 0 : 0 : 0 1 : 

KERNELS=="6: 0:0:0" 

SUBSYSTEMS=="SCSi" 

DRIVERS=="sd" 

ATTRS{rev}=="l . 00" 

ATTRS{model}=="X250, D560Z, C350Z" 

ATTRS{vendor}=="OLYMPUS " 

ATTRS{scsi_level}=="3" 

ATTRS{type}=="0" 

</pre></blockquote> 

<p> 

My rule: 

</p> 

<blockquote><pre>KERNEL=="sd?l", SUBSYSTEMS=="scsi", 

ATTRS{model}=="X250, D560Z, C350Z" , SYMLINK+="camera"</pre></blockquote> 

<a name="example-usbhdd"x/a> 

<h3>USB Hard Disk</h3> 

<p> 

A USB hard disk is comparable to the USB camera I described above, however typical 
usage patterns are different. In the camera example, I explained that I am not 
interested in the sdb node - it's only real use is for partitioning (e.g. with 
fdisk), but why would I want to partition my camera!? 

</p> 

<p> 

Of course, if you have a 100GB USB hard disk, it is perfectly understandable that 
you might want to partition it, in which case we can take advantage of udev's 
string substitutions: 

</p> 

<blockquotexpre>KERNEL=="sd*", sUBSYSTEMS=="scsi", ATTRS{model}=="USB 2.0 Storage 
Device", SYMLlNK+="usbhd%n"</prex/blockquote> 

<p> 

This rule creates symlinks such as: 



</p> 

<ul> 

<li><em>/dev/usbhd</em> - The fdiskable node</li> 

<li><em>/dev/usbhdl</em> - The first partition (mountable)</li> 
<li><em>/dev/usbhd2</em> - The second partition (mountable)</li> 

</ul> 

<a name="example-usbcardreader"x/a> 

<h3>USB Card Reader</h3> 

<p> 

USB card readers (CompactFlash, SmartMedia, etc) are yet another range of USB 
storage devices which have different usage requirements. 

</p> 

<p> 

These devices typically do not inform the host computer upon media change. So, if 
you plug in the device with no media, and then insert a card, the computer does not 
realise, and you do not have your mountable sdbl partition node for the media. 

</p> 

<p> 

One possible solution is to take advantage of the <em>all_partitions</em> option, 
which will create 16 partition nodes for every block device that the rule matches: 

</p> 

<blockquotexpre>KERNEL="sd*\ SUBSYSTEMS=="scsi", ATTRS{model}=="USB 2.0 
CompactFlash Reader", SYMLINK+="cf rdr%n", 

OPTIONS+="all_par tit ions "</pre></blockquote> 

You will now have nodes named: cfrdr, cfrdrl, cfrdr2, cfrdr3, ..., cfrdrlS. 

<a name="example-pilot"x/a> 

<h3>USB Palm Pilot</h3> 

<p> 

These devices work as USB-serial devices, so by default, you only get the 
<em>ttyUSBl</em> device node. The palm utilities rely on <em>/dev/pilot</em>, so 
many users will want to use a rule to provide this. 

</p> 

<p> 

<a href ="http : //www. clasohm . com/blog/one -entry?entry%5fid=12096">Cars ten Clasohm ' s 
blog post</a> appears to be the definitive source for this. Carsten's rule is shown 
below: 

</p> 

<blockquote><pre>SUBSYSTEMS=="usb", ATTRS{product}=="Palm Handheld", 
KERNEL=="ttyUSB* " , SYMLINK+="pilot"</pre></blockquote> 

<p> 

Note that the product string seems to vary from product to product, so make sure 
that you check (using udevadm info) which one applies to you. 

</p> 

<a name="example-cdrom"x/a> 

<h3>CD/DVD drives</h3> 



<p> 

I have two optical drives in this computer: a DVD reader (hdc), and a DVD rewriter 
(hdd). I do not expect these device nodes to change, unless I physically rewire my 
system. However, many users like to have device nodes such as <em>/dev/dvd</em> for 
convenience . 

</p> 

<p> 

As we know the KERNEL names for these devices, rule writing is simple. Here are 
some examples for my system: 

</p> 

<blockquote><pre> 

SUBSYSTEM=="blOCk" , KERNEL=="hdc" , SYMLINK+="dvd" , GROUP="cdrom" 

SUBSYSTEM=="block" , KERNEL=="hdd" , SYMLINK+="dvdrw" , GROUP="cdrom" 
</pre></blockquote> 

<a name="example-netif "></a> 

<h3>Network interfaces</h3> 

<p> 

Even though they are referenced by names, network interfaces typically do not have 
device nodes associated with them. Despite that, the rule writing process is almost 
identical . 

</p> 

<p> 

It makes sense to simply match the MAC address of your interface in the rule, as 
this is unique. However, make sure that you use the <em>exact</em> MAC address as 
shown as udevadm info, because if you do not match the case exactly, your rule will 
not work. 

</p> 

<blockquote><pre> 

# udevadm info -a -p /sys/class/net/ethO 

looking at class device '/sys/class/net/ethO' : 

KERNEL=="ethO" 

ATTR{address}=="00 : 52 : 8b : d5 : 04 : 48" 

</pre></blockquote> 

<p> 

Here is my rule: 

</p> 

<blockquotexpre>KERNEL=="eth* " , ATTR{address}=="00 : 52 : 8b : d5 : 04 : 48" , 
NAME="lan"</pre></blockquote> 

<p> 

You will need to reload the net driver for this rule to take effect. You can either 
unload and reload the module, or simply reboot the system. You will also need to 
reconfigure your system to use "lan" rather than "eth0". I had some troubles 
getting this going (the interface wasn't being renamed) until I had completely 
dropped all references to eth0. 

After that, you should be able to use "lan" instead of "eth0" in any calls to 
ifconfig or similar utilities. 

</p> 


<h2>Testing and debugging</h2> 



<a name="testing"x/a> 

<h3>Putting your rules into action</h3> 


<p> 

Assuming you are on a recent kernel with <em>inotify</em> support, udev will 
automatically monitor your rules directory and automatically pick up any 
modifications you make to the rule files. 

</p> 

<p> 

Despite this, udev will not automatically reprocess all devices and attempt to 
apply the new rule(s). For example, if you write a rule to add an extra symbolic 
link for your camera while your camera is plugged in, you cannot expect the extra 
symbolic link to show up right away. 

</p> 

<p> 

To make the symbolic link show up, you can either disconnect and reconnect your 
camera, or alternatively in the case of non-removable devices, you can run 
<b>udevadm trigger</b>. 

</p> 

<a name="udevtest"></a> 

<h3>udevadm test</h3> 

<p> 

If you know the top-level device path in sysfs, you can use <b>udevadm test</b> to 
show the actions which udev would take. This may help you debug your rules. For 
example, assuming you want to debug a rule which acts on 
<em>/sys/class/sound/dsp</em> : 

</p> 

<blockquote><pre> 

# udevadm test /class/sound/dsp 

main: looking at device '/class/sound/dsp' from subsystem 'sound' 
udev_rules_get_name : add symlink ' dsp ' 

udev_rules_get_name: rule applied, 'dsp' becomes 'sound/dsp' 
udev_device_event : device '/class/sound/dsp' already known, remove possible 
symlinks 

udev_node_add : creating device node ' /dev/sound/dsp ' , major = '14', minor = '3', 
mode = '0660', uid = '0', gid = '18' 

udev_node_add : creating symlink '/dev/dsp' to 'sound/dsp' 

</pre></blockquote> 

<p> 

Note the <em>/sys</em> prefix was removed from the udevadm test test command line 
argument, this is because udevadm test operates on device paths. 

</p> 

<a name="author"x/a> 
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